home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Almathera Ten Pack 2: CDPD 1
/
Almathera Ten on Ten - Disc 2: CDPD 1.iso
/
pd
/
276-300
/
283
/
bref
/
bref.doc
< prev
next >
Wrap
Text File
|
1995-03-14
|
7KB
|
216 lines
Documentation for Program BREF Nov 1989 Version 1.01
Dick Taylor Glastonbury, Connecticut USA
Contents
1. Components
2. What does BREF do?
3. Restrictions
4. How to use
5. Program history
6. Program promo
7. SAVE'ing AmigaBASIC in ASCII
8. Program limitations
9. Options
10. Potential Stack problem
11. Programming notes
12. BREF communications
-------------------------
| E S S E N T I A L S |
-------------------------
1. COMPONENTS
bref -- executable
bref.c -- C language source code
bref.doc -- documentation
2. WHAT DOES BREF DO?
BREF produces a Cross Reference Table for AmigaBASIC code. This consists
of a listing of the BASIC code with lines sequentially numbered, plus a
table showing all variables/labels (names) used in the code and the line
numbers where used.
3. RESTRICTIONS
a. The AmigaBasic code for input to BREF must be in ASCII format, not the
default binary.
b. Run BREF from CLI or SHELL.
4. HOW TO USE
Use output redirection >prt: to send output to the printer.
In CLI or SHELL:
bref >prt: your.prog.name
If you omit output redirection, output goes to the screen.
Specify pathname as needed for both BREF and your program.
---------------------------------------------
| B A C K G R O U N D & D E T A I L S |
---------------------------------------------
5. PROGRAM HISTORY
Program BREF is a modification of CREF, the cross referencer for C
language programs. I obtained CREF from Fred Fish Disk #166. The original
CREF was written in May 1981 by Mike Edmonds, for another computer system.
CREF was ported to the Amiga in September 1987 by Joel Swank.
In 1989 I modified CREF to produce BREF.
6. PROGRAM PROMO
BASIC programmers will find BREF to be of interest. You will need to get
the printed output to attain and appreciate its full usefulness.
Screen output may be useful in some situations. If you haven't used a
Cross Referencer before, please accept my recomendation that this is a
HIGHLY VALUABLE PROGRAMMING TOOL for any program longer than a page or two.
Cross Referencing Table is a widely available option on many main-frame
compilers, and is a heavily used tool among professional programmers.
(Memo to Commodore/Microsoft: You could make a substantial
enhancement to AmigaBASIC by supplying a BASIC Cross Reference
Utility with one of the Operating System updates. Until this
is available, BREF can be used for this function.)
7. SAVE'ing AMIGABASIC IN ASCII
In order to use BREF, you need to save your BASIC code in ASCII. Use the
BASIC output window for this:
SAVE "your.prog.name",A
Those double quotes are needed, just as shown. You can't save in ASCII
from the "SAVE" or "SAVE AS" requester windows. To save on disk space, I
often save the ASCII version to RAM. For instance:
SAVE "ram:your.prog.name",A
Of course, then be sure to include the pathname ram: in starting BREF. The
default format for saved AmigaBASIC code is binary. If you try to run BREF
with saved binary, the run aborts with this message:
"File your.prog.name is binary, can't process. ASCII req."
8. PROGRAM LIMITATIONS
a. AmigaBASIC allows names up to 40 characters in length. Program BREF,
however, handles names only up to 15 characters long. This causes names
of more than 15 characters to be split, appearing as more than one name in
the cross reference table.
b. BREF uses up to four digits (9999) for the sequential line numbers
assigned to the code listing. This is sufficient for a listing of 180+
pages. Hopefully this will accomodate 99.9% of BASIC programs! If you
want to use BREF on a program larger than 9,999 lines, you'll need to
split it into parts.
9. OPTIONS
The first letter of each option may be upper or lower case. Here is an
example of running BREF with options:
bref >prt: -Q -W132 your.prog.name
Specify as many options as needed; place preceding the program name, any
order. Precede each option with a minus sign.
-Q -don't print the BASIC code listing (Quiet).
-Wnnn -set page Width to nnn instead of default 80; max is 132.
-Lnnn -set page Length to nnn instead of default 66.
-Hccc -set page Heading to 'ccc' rather than the program name.
-S -Suppress Form Feeds; useful for screen output.
-K -show the BASIC Keywords in the the cross ref table.
Default-- the BASIC keywords are omitted.
-E -print the BASIC code 12 char's/inch (Elite type) instead of
the default 10 char's/inch. For a default 80-char
line, this produces a 96-char line. This tends to cut down on
the annoying lines which are split into 2 lines on printing.
-? -display this list.
A single invocation of BREF may specify multiple program names. Example:
bref >prt: program1 program2 ...
This produces one cross reference table for the specified programs.
Alternatively, the program name(s) as shown may be omitted, and then BREF
reads STDIN for its input. In this case use input redirection. Example:
bref <your.prog.name >prt:
For this case, the options follow >prt:.
10. POTENTIAL STACK PROBLEM
BREF makes heavy use of recursion, which is a stack-intensive operation.
In running very large BASIC programs through BREF, it is possible that you
may crash the system (guru or whatever) due to exceeding the stack (default
stack size is 4000). If this happens, try increasing the stack to 8000 and
rerun. The largest program I have run is a little over 1,000 lines-- no
problem with the default stack.
11. PROGRAMMING NOTES
a. BREF was compiled with Manx Aztec C v. 3.6:
cc bref.c
ln bref.o -lc
b. Program changes to CREF to produce BREF:
-AmigaBASIC keyword list, 202 items
-Char set for word definition: drop # _ add . % & ! # $
-Comment definition: ' or REM
-Default print line 80 char (was 132)
-Add options -S, -K, -E
-Assigned line no. print field width 4 char (was 6)
c. I encountered significant trouble with implementing the AmigaBASIC
keyword list. When I entered the list in alphabetic order and tried to run
with stack = 4000, it crashed (guru) in a variety of places depending on
other system factors. It turns out to be a problem caused by heavy
recursion usage -- entering items (both keywords and program words) into a
tree. The solution was to enter the keywords in binary search order,
thereby minimizing recursion level depth. With this arrangement of
keywords I've had no problem running with stack of 4000.
12. FOR BREF COMMUNICATIONS--
Dick Taylor Found a bug?
99 Valley View Rd Want a program change?
Glastonbury CT 06033 Editorial remarks?
USA Your comments are welcome!!!
Tel (203) 633-0100